Skip to main content

Access Control

ApertureDB controls database access through roles assigned to users. A role defines a set of permissions, and a user receives the combined permissions of all assigned roles. Database users and tokens are separate from accounts used to sign into ApertureDB Cloud. For the UI workflow, see collaboration setup.

Role​

A role defines permissions over objects, indexes, and users/roles. Create, Read, Update, and Delete (CRUD) permissions apply separately to each resource category:

  • Objects: elements in the database (app-defined entities, images, videos, etc)

  • Indexes: indexes over the properties of the objects.

  • Users/Roles: access control information.

Permissions for users and roles control account administration: creating, reading, updating, and deleting users or roles.

Each role has a name.

Role names do not imply permissions. For example, reader can grant only objects.read. The researcher example in CreateRole grants both object creation and reading.

Every database has an admin role with all permissions and an admin user assigned to that role.

User​

A user is a database identity with a username, a password, and optionally a set of personal tokens.

The default username is admin. Usernames contain at least four characters, contain no whitespace, and cannot begin with an underscore (_).

On first initialization, the admin password is taken from master_key in Configuration File, with a nonempty ADB_MASTER_KEY environment variable taking precedence. Changing the bootstrap key does not reset an existing admin password; use UpdateUser. Set a strong initial key even though bootstrap does not apply the CreateUser/UpdateUser password check.

For CreateUser and UpdateUser, a password must contain at least 10 characters, including a letter, a digit, and punctuation. Whitespace and other unsupported characters are rejected. Store passwords and tokens outside source control.

A personal token (adbp_ prefix) authenticates in place of a password. GenerateToken generates its value; UpdateUser assigns it to a user. Generating a token alone grants no access.

Authenticate returns a session token (adbs_) for query messages and a refresh token (adbr_) for RefreshToken. The client SDK manages sessions and refresh automatically. Session and refresh token lifetimes are configured in Configuration File. Keep the full personal token when issuing it: user-detail responses expose only its identifying tag.

Create and verify a limited user​

Connect as an administrator using Connect and verify the deployment. Run each step as a separate request and check for status 0 before continuing. The names below must not already exist; choose fresh names in a shared database.

First create a role that can read objects, with all other permissions omitted (and therefore false):

[{"CreateRole": {"name": "reader", "objects": {"read": true}}}]

Then create its user, replacing the password placeholder with a strong secret:

[{"CreateUser": {
  "username": "reader_user",
  "password": "<strong-password-with-digits-and-punctuation>",
  "roles": ["reader"]
}}]

Open a new client connection as reader_user. A read such as the following is allowed, even if the class currently has no entities:

[{"FindEntity": {"with_class": "PermissionCheck", "results": {"count": true}}}]

On the same connection, an attempt to add an entity returns a nonzero permission error and creates no entity:

[{"AddEntity": {"class": "PermissionCheck"}}]

Check the error info with Responses. If the write succeeds, inspect all assigned roles with the administrator’s GetUserDetails request; another role can grant the permission. Keep permission checks separate from production writes.

Issue, use, and revoke a personal token​

  1. On the administrator connection, run [{"GenerateToken": {}}] and securely retain the returned token value.

  2. Assign that value to the limited user:

    [{"UpdateUser": {
      "username": "reader_user",
      "add_tokens": ["<returned-adbp-token>"]
    }}]

  3. Use a new connection and authenticate with the token:

    [{"Authenticate": {"token": "<returned-adbp-token>"}}]

    Use the returned session token for subsequent requests, or let the SDK manage it. Repeat the allowed read and denied write above.

  4. On the administrator connection, revoke the personal token:

    [{"UpdateUser": {
      "username": "reader_user",
      "remove_tokens": ["<returned-adbp-token>"]
    }}]

    Verify rejection by authenticating on a new connection with that personal token. Removal prevents new authentication with it; it does not establish immediate invalidation of sessions already issued from it.

Remove the example user and then its role with RemoveUser and RemoveRole when finished. For credentials authorizing access to remote media, see CreateCredential and HTTPS origins; those credentials serve a different purpose from user authentication.